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ABOUT THIS CHAPTER 


This chapter describes the Device Manager, the part of the Operating System that 
controls the exchange of information between a Macintosh application and 
devices. It gives general information about using and writing device drivers, 
and also discusses interrupts: how the Macintosh uses them and how you can use 
them if you're writing your own device driver. 


Note: Specific information about the standard Macintosh drivers is 
contained in separate chapters. 


You should already be familiar with resources, as discussed in the Resource 
Manager section. 
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ABOUT THE DEVICE MANAGER 


Note: The extensions to the Device Manager described in this chapter were 
Originally documented in Inside Macintosh, Volumes IV and V. As such, 
the Volume IV information refers to the 128K ROM and System file 
version 3.2 and later, while the Volume V information refers to the 
Macintosh SE and Macintosh II ROMs and System file version 4.1 and 
later. The sections of this chapter that cover these extensions are 
so noted. 


The Device Manager is the part of the Operating System that handles 
communication between applications and devices. A device is a part of the 
Macintosh, or a piece of external equipment, that can transfer information into 
or out of the Macintosh. Macintosh devices include disk drives, two serial 
communications ports, and printers. 


Note: The display screen is not a device; drawing on the screen is 
handled by QuickDraw. 


There are two kinds of devices: character devices and block devices. A 
character device reads or writes a stream of characters, or bytes, one at a 
time: It can neither skip bytes nor go back to a previous byte. A character 
device is used to get information from or send information to the world outside 
of the Operating System and memory: It can be an input device, an output 
device, or an input/output device. The serial ports and printers are all 
character devices. 


A block device reads and writes blocks of bytes at a time; it can read or write 
any accessible block on demand. Block devices are usually used to store and 
retrieve information; for example, disk drives are block devices. 


Applications communicate with devices through the Device Manager—either directly 
or indirectly (through another part of the Operating System or 

Toolbox). For example, an application can communicate with a disk drive directly 
via the Device Manager, or indirectly via the File Manager (which calls the 
Device Manager). The Device Manager doesn't manipulate devices directly; it 
calls device drivers that do (see Figure 1). Device drivers are programs that 
take data coming from the Device Manager and convert them into actions of 
devices, or convert device actions into data for the Device Manager to process. 


The Operating System includes three standard device drivers in ROM: the Disk 
Driver, the Sound Driver, and the ROM Serial Driver. There are also a number of 
standard RAM drivers, including the Printer Driver, the RAM Serial Driver, the 
AppleTalk drivers, and desk accessories. RAM drivers are resources, and are read 
from the system resource file as needed. 


You can add other drivers independently or build on top of the existing drivers 
(for example, the Printer Driver is built on top of the Serial Driver); the 
section "Writing Your Own Device Drivers" describes how to do this. Desk 
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accessories are a special type of device driver, and are manipulated via the 
routines of the Desk Manager. 


Figure 1-Communication with Devices 
Figure 1—Communication with Devices 


Warning: Information about desk accessories covered in the Desk Manager 
chapter is not repeated here. Some information in this chapter 
may not apply to desk accessories. 


A device driver can be either open or closed. The Sound Driver and Disk Driver 
are opened when the system starts up; the rest of the drivers are opened at the 
specific request of an application. After a driver has been opened, an 
application can read data from and write data to it. You can close device 
drivers that are no longer in use, and recover the memory used by them. Up to 32 
device drivers may be open at any one time. 


Before it's opened, you identify a device driver by its driver name; after it's 
opened, you identify it by its reference number. A driver name consists of a 
period (.) followed by any sequence of 1 to 254 printing characters. A RAM 
driver's name is the same as its resource name. You can use uppercase and 
lowercase letters when naming drivers, but the Device Manager ignores case when 
comparing names (it doesn't ignore diacritical marks). 


Note: Although device driver names can be quite long, there's little 
reason for them to be more than a few characters in length. 
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The Device Manager assigns each open device driver a driver reference number, 
from —1 to —32, that's used instead of its driver name to refer to it. 


Most communication between an application and an open device driver occurs by 
reading and writing data. Data read from a driver is placed in the 
application's data buffer, and data written to a driver is taken from the 
application's data buffer. A data buffer is memory allocated by the application 
for communication with drivers. 


In addition to data that's read from or written to device drivers, drivers may 
require or provide other information. Information transmitted to a driver by an 
application is called control information; information provided by a driver is 
called status information. Control information may select modes of operation, 
start or stop processes, enable buffers, choose protocols, and so on. Status 
information may indicate the current mode of operation, the readiness of the 
device, the occurrence of errors, and so on. Each device driver may respond to a 
number of different types of control information and may provide a number of 
different types of status information. 


Each of the standard Macintosh drivers includes predefined calls for 
transmitting control information and receiving status information. Explanations 
of these calls can be found in the chapters describing the drivers. 


Note: The extensions to the Device Manager described in the following 
paragraphs were originally documented in Inside Macintosh, Volume IV. 
As such, this information refers to the 128K ROMs and System file 
version 3.2 and later. 


While no new routines have been added to the Device Manager with the Macintosh 
Plus, the handling of the existing routines has been significantly improved. 


When an Open call is made, installed drivers are searched first (before 
resources) to avoid replacing a current driver; this search is done by name so 
be sure that your driver's name is in the driver header. ALl drivers, exclusive 
of desk accessories, must have a name that begins with a period; otherwise, the 
Open call is passed on to the File Manager. 


If a driver is already open, Open calls will not be sent to the driver's open 
routine, preserving its device control entry. A desk accessory will, however, 
receive another call (certain desk accessories count on this). 


If a driver fails to open because of a resource load problem, the Open call 
terminates with the appropriate error code instead of being passed on to the 
File Manager (which would usually return the result code fnfErr). If a driver 
returns a negative result code in register DQ from an Open call, the result code 
is passed back and the driver is not opened. If a driver returns the result code 
closeErr in register DO from a Close call, this result code is passed back and 
the driver is not closed. 


Open, Close, Read, Write, Control, and Status return all results in the ioResult 
field as well as in register DO. A KillIO call is passed to the driver only if 
it's open and enabled for Control calls. 
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The number of device control entries in the 128K ROM has been increased from 32 
to 48. The unit table is now a 192-byte nonrelocatable block containing 48 
four-byte entries; the standard unit table assignments are as follows: 


Unit Number Device 


0 Reserved 
Hard disk driver: Macintosh XL internal or Hard Disk 20 external 
2 .Print driver 
3 .Sound driver 
4 .Sony driver 
5 Modem port asynchronous driver input (.AIn) 
6 Modem port asynchronous driver output (.AQut) 
7 Printer port asynchronous driver input (.BIn) 
8 Printer port asynchronous driver output (.BOut) 
9 AppleTalk .MPP driver 
10 AppleTalk .ATP driver 
11 Reserved 
12-26 Desk accessories in System file 
27-31 Desk accessories in application files 
32-39 SCSI drivers Q-7 
40-47 Reserved 


Note: The extensions to the Device Manager described in the following 
paragraphs were originally documented in Inside Macintosh, Volume V. 
As such, this information refers to the Macintosh SE and Macintosh II 
ROMs and System file version 4.1 and later. 


New modifications have been made to the Device Manager to support slot devices. 


Reader's guide: You need the information in the slot-related sections of 
this chapter only if your application uses a specific card 
(other than a standard video card) that plugs into a NuBus™ 
slot on the Macintosh II. 


These slot-related sections cover the following subjects: 


the parts of the system startup procedure that affect slot devices 
how the Open call now handles slot devices 

how interrupts originating in slot devices are processed 

how the new Chooser works with slot devices 


e 
e 
e 
e 


You'll also need to be familiar with 


° the Start Manager 
° the Slot Manager 
° the parts of the book "Designing Cards and Drivers for Macintosh 
II and Macintosh SE" that pertain to the device your application uses. 
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USING THE DEVICE MANAGER 


You can call Device Manager routines via three different methods: high-level 
Pascal calls, low-level Pascal calls, and assembly language. The high-level 
Pascal calls are designed for Pascal programmers interested in using the Device 
Manager in a simple manner; they provide adequate device I/O and don't require 
much special knowledge to use. The low-level Pascal and assembly-language calls 
are designed for advanced Pascal programmers and assembly-language programmers 
interested in using the Device Manager to its fullest capacity; they require 
some special knowledge to be used most effectively. 


Note: The names used to refer to routines here are actually 
assembly-language macro names for the low-level routines, 
but the Pascal routine names are very similar. 


The Device Manager is automatically initialized each time the system starts up. 


Before an application can exchange information with a device driver, the driver 
must be opened. The Sound Driver and Disk Driver are opened when the system 
starts up; for other drivers, the application must call Open. The Open routine 
will return the driver reference number that you'll use every time you want to 
refer to that device driver. 


An application can send data from its data buffer to an open driver with a Write 
call, and transfer data from an open driver to its data buffer with Read. An 
application passes control information to a device driver by calling Control, 
and receives status information from a driver by calling Status. 


Whenever you want to stop a device driver from completing I/O initiated by a 
Read, Write, Control, or Status call, call KillIO. KillIO halts any current I/0 
and deletes any pending I/0. 


When you're through using a driver, call Close. Close forces the device driver 
to complete any pending I/0, and then releases all the memory used by the 
driver. 
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DEVICE MANAGER ROUTINES 


This section describes the Device Manager routines used to call drivers. It's 
divided into two parts: The first describes all the high-level Pascal routines 
of the Device Manager, and the second presents information about calling the 
low-level Pascal and assembly-language routines. 


All the Device Manager routines in this section return an integer result code of 
type OSErr. Each routine description lists all of the applicable result codes, 
along with a short description of what the result code means. Lengthier 
explanations of all the result codes can be found in the summary at the end of 
this chapter. 


High-Level Device Manager Routines 


Note: As described in the File Manager chapter, the FSRead and FSWrite 
routines are also used to read from and write to files. 


FUNCTION OpenDriver (name: Str255; VAR refNum: INTEGER) : OSErr; [Not in ROM] 


OpenDriver opens the device driver specified by name and returns its reference 
number in refNum. 


Result codes noErr No error 
badUnitErr Bad reference number 
diInsteErr Couldn't find driver in resource file 
openErr Driver can't perform the requested 
reading or writing 
unitEmptyErr Bad reference number 


FUNCTION CloseDriver (refNum: INTEGER) : OSErr; [Not in ROM] 


CloseDriver closes the device driver having the reference number refNum. Any 
pending I/O is completed, and the memory used by the driver is released. 


Warning: Before using this command to close a particular driver, refer 
to the chapter describing the driver for the consequences of 


closing it. 
Result codes noErr No error 
badUnitErr Bad reference number 
dRemoveErr Attempt to remove an open driver 
unitEmptyErr Bad reference number 


FUNCTION FSRead (refNum: INTEGER; VAR count: LONGINT; 
buffPtr: Ptr) : OSErr; [Not in ROM] 
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FSRead attempts to read the number of bytes specified by the count parameter 
from the open device driver having the reference number refNum, and transfer 
them to the data buffer pointed to by buffPtr. After the read operation is 
completed, the number of bytes actually read is returned in the count parameter. 


Result codes noErr No error 
badUnitErr Bad reference number 
notOpenErr Driver isn't open 
unitEmptyErr Bad reference number 
readErr Driver can't respond to Read calls 


FUNCTION FSWrite (refNum: INTEGER; VAR count: LONGINT; 
buffPtr: Ptr) : OSErr; [Not in ROM] 


FSWrite takes the number of bytes specified by the count parameter from the 
buffer pointed to by buffPtr and attempts to write them to the open device 
driver having the reference number refNum. After the write operation is 
completed, the number of bytes actually written is returned in the count 
parameter. 


Result codes noErr No error 
badUnitErr Bad reference number 
notOpenErr Driver isn't open 
unitEmptyErr Bad reference number 
writErr Driver can't respond to Write calls 


FUNCTION Control (refNum: INTEGER; csCode: INTEGER; 
csParamPtr: Ptr) : OSErr; [Not in ROM] 


Control sends control information to the device driver having the reference 
number refNum. The type of information sent is specified by csCode, and the 
information itself is pointed to by csParamPtr. The values passed in csCode and 
pointed to by csParamPtr depend on the driver being called. 


Result codes noErr No error 
badUnitErr Bad reference number 
notOpenErr Driver isn't open 
unitEmptyErr Bad reference number 
controlErr Driver can't respond to this Control call 


FUNCTION Status (refNum: INTEGER; csCode: INTEGER; 
csParamPtr: Ptr) : OSErr; [Not in ROM] 


Status returns status information about the device driver having the reference 
number refNum. The type of information returned is specified by csCode, and the 
information itself is pointed to by csParamPtr. The values passed in csCode and 
pointed to by csParamPtr depend on the driver being called. 


Result codes noErr No error 
badUnitErr Bad reference number 
notOpenErr Driver isn't open 
unitEmptyErr Bad reference number 
statusErr Driver can't respond to this Status call 
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FUNCTION KillIO (refNum: INTEGER) : OSErr; [Not in ROM] 


KillIO terminates all current and pending I/0 with the device driver having the 
reference number refNum. 


Result codes noErr No error 
badUnitErr Bad reference number 
unitEmptyErr Bad reference number 


Low-Level Device Manager Routines 


This section contains special information for programmers using the low-level 
Pascal or assembly-language routines of the Device Manager, and describes them 
in detail. 


Note: The Device Manager routines for writing device drivers are 
described in the section "Writing Your Own Device Drivers". 


ALL low-level Device Manager routines can be executed either synchronously 
(meaning that the application can't continue until the routine is completed) or 
asynchronously (meaning that the application is free to perform other tasks 
while the routine is executing). Some cannot be executed asynchronously, because 
they use the Memory Manager to allocate and release memory. 


When an application calls a Device Manager routine asynchronously, an I/0 
request is placed in the driver I/O queue, and control returns to the calling 
program—possibly even before the actual I/O is completed. Requests are taken 
from the queue one at a time, and processed; meanwhile, the calling program is 
free to work on other things. 


The calling program may specify a completion routine to be executed at the end 
of an asynchronous operation. 


Routine parameters passed by an application to the Device Manager and returned 
by the Device Manager to an application are contained in a parameter block, 
which is a data structure in the heap or stack. All low-level Pascal calls to 
the Device Manager are of the form 


FUNCTION PBCallName (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


PBCallName is the name of the routine. ParamBlock points to the parameter block 
containing the parameters for the routine. If async is TRUE, the call is 
executed asynchronously; otherwise the call is executed synchronously. Each call 
returns an integer result code of type OSErr. 


Assembly-language note: When you call a Device Manager routine, AO must 
point to a parameter block containing the 
parameters for the routine. If you want the 
routine to be executed asynchronously, set bit 10 
of the routine trap word. You can do this by 
Supplying the word ASYNC as the second argument 
to the routine macro. For example: 
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_Read ,ASYNC 


You can set or test bit 10 of a trap word by using 
the global constant asyncTrpBit. 


If you want a routine to be executed immediately 
(bypassing the driver I/O queue), set bit 9 of the 
routine trap word. This can be accomplished by 
Supplying the word IMMED as the second argument 

to the routine macro. (The driver must be able to 
handle immediate calls for this to work.) For example: 


“Write ,IMMED 


You can set or test bit 9 of a trap word by using 
the global constant noQueueBit. You can specify 
either ASYNC or IMMED, but not both. (The syntax 
shown above applies to the Macintosh Programmers 
Workshop Assembler; programmers using another 
development system should consult its documentation 
for the proper syntax. ) 


All routines return a result code in DO. 
Routine Parameters 


There are two different kinds of parameter blocks you'll pass to Device Manager 
routines: one for I/O routines and another for Control and Status calls. 


The lengthy, variable-length data structure of a parameter block is given below. 
The Device Manager and File Manager use this same data structure, but only the 
parts relevant to the Device Manager are discussed here. Each kind of parameter 
block contains eight fields of standard information and three to nine fields of 
additional information: 


TYPE ParamBlkType = (ioParam, fileParam, volumeParam, cntrlParam) ; 
ParamBlockRec = RECORD 

qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
ioTrap: INTEGER; {routine trap} 
ioCmdAddr: Ptr; {routine address} 
ioCompletion: ProcPtr; {completion routine} 
ioResult: OSErr; {result code} 
ioNamePtr: StringPtr; {driver name} 
ioVRefNum: INTEGER; {volume reference or } 


{ drive number} 
CASE ParamBlkType OF 


ioParam: 

. . . {I/0 routine parameters} 
fileParam: 

: . {used by the File Manager} 
volumeParam: 
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; . {used by the File Manager} 
cntrlParam: 
. {Control and Status call parameters} 
END; 


ParmBLkPtr = “ParamBlockRec; 


The first four fields in each parameter block are handled entirely by the Device 
Manager, and most programmers needn't be concerned with them; programmers who 
are interested in them should see the section "The Structure of a Device 
Driver". 


IOCompletion contains a pointer to a completion routine to be executed at the 
end of an asynchronous call; it should be NIL for asynchronous calls with no 
completion routine, and is automatically set to NIL for all synchronous calls. 


Warning: Completion routines are executed at the interrupt level and must 
preserve all registers other than AO, Al, and DOQ-D2. Your completion 
routine must not make any calls to the Memory Manager, directly or 
indirectly, and can't depend on handles to unlocked blocks being 
valid. If it uses application globals, it must also ensure that 
register A5 contains the address of the boundary between the 
application globals and the application parameters; for details, 
see SetCurrentA5 and SetA5 in Macintosh Technical Note #208. 


eeeClick on the X-Ref button, and refer to Technical Note #208. ¢ee 


Assembly-language note: When your completion routine is called, register AO 
points to the parameter block of the asynchronous 
call and register DO contains the result code. 


Routines that are executed asynchronously return control to the calling program 
with the result code noErr as soon as the call is placed in the driver I/0 
queue. This isn't an indication of successful call completion, but simply 
indicates that the call was successfully queued. To determine when the call is 
actually completed, you can poll the ioResult field; this field is set to 1 when 
the call is made, and receives the actual result code upon completion of the 
call. Completion routines are executed after the result code is placed in 
ioResult. 


IONamePtr is a pointer to the name of a driver and is used only for calls to the 
Open function. IOVRefNum is used by the Disk Driver to identify drives. 


I/O routines use the following additional fields: 


ioParam: 
(ioRefNum: INTEGER; {driver reference number} 
ioVersNum: SignedByte; {not used} 
ioPermssn: SignedByte; {read/write permission} 
ioMisc: Ptr; {not used} 
ioBuffer: Ptr; {pointer to data buffer} 
ioReqCount: LONGINT; {requested number of bytes} 
ioActCount: LONGINT; factual number of bytes} 
ioPosMode: INTEGER; {positioning mode} 
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ioPosOffset: LONGINT); {positioning offset} 


IOPermssn requests permission to read from or write to a driver when the driver 
is opened, and must contain one of the following values: 


CONST fsCurPerm = 0; {whatever is currently allowed} 
fsRdPerm = 1; {request to read only} 
fsWrPerm = 2; {request to write only} 
fsRdWrPerm = 3; {request to read and write} 


This request is compared with the capabilities of the driver (some drivers are 
read-only, some are write-only). If the driver is incapable of performing as 
requested, a result code indicating the error is returned. 


I0Buffer points to a data buffer into which data is written by Read calls and 
from which data is read by Write calls. I0ReqCount specifies the requested 
number of bytes to be read or written. I0ActCount contains the number of bytes 
actually read or written. 


IOPosMode and ioPosOffset contain positioning information used for Read and 
Write calls by drivers of block devices. I0PosMode contains the positioning 
mode; bits 0 and 1 indicate where an operation should begin relative to the 
physical beginning of the block-formatted medium (such as a disk). You can use 
the following predefined constants to test or set the value of these bits: 


CONST fsAtMark = 0; fat current position} 
fsFromStar = 1; {offset relative to beginning of medium} 
fsFromMark = 3; {offset relative to current position} 


I0PosOffset specifies the byte offset (either positive or negative), relative to 
the position specified by the positioning mode, where the operation will be 
performed (except when the positioning mode is fsAtMark, in which case 
ioPosOffset is ignored). I0PosOffset must be a 512-byte multiple. 


To verify that data written to a block device matches the data in memory, make a 
Read call right after the Write call. The parameters for a read-verify operation 
are the same as for a standard Read call, except that the following constant 
must be added to the positioning mode: 

CONST rdVerify = 64; {read-verify mode} 
The result code ioErr is returned if any of the data doesn't match. 


Control and Status calls use three additional fields: 


cntrlParam: 
(ioCRefNum: INTEGER; {driver reference number} 
csCode: INTEGER; {type of Control or Status call} 
csParam: ARRAY[O..10] OF INTEGER); {control or status information} 


IOCRefNum contains the reference number of the device driver. The csCode field 
contains a number identifying the type of call; this number may be interpreted 
differently by each driver. The csParam field contains the control or status 
information for the call; it's declared as up to 22 bytes of information because 
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its exact contents will vary from one Control or Status call to the next. To 
store information in this field, you must perform the proper type 
coercion.Routine Descriptions 


This section describes the procedures and functions. Each routine description 
includes the low-level Pascal form of the call and the routine's assembly- 
language macro. A list of the fields in the parameter block affected by the call 
is also given. 


Assembly-language note: The field names given in these descriptions are 
those of the ParamBlockRec data type; see the 
summary at the end of this chapter for the names 
of the corresponding assembly-language offsets. 
(The names for some offsets differ from their 
Pascal equivalents, and in certain cases more than 
One name for the same offset is provided. ) 


The number next to each parameter name indicates the byte offset of the 
parameter from the start of the parameter block pointed to by register AQ; only 
assembly- language programmers need be concerned with it. An arrow next to each 
parameter name indicates whether it's an input, output, or input/output 
parameter: 


Arrow Meaning 
--> Parameter is passed to the routine 
<-- Parameter is returned by the routine 
<-> Parameter is passed to and returned by the routine 


Note: As described in the File Manager chapter, the Open and Close 
functions are also used to open and close files. 


FUNCTION PBOpen (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Parameter block 


--> 12 ioCompletion pointer 
<s- 16 ioResult word 
--> 18 ioNamePtr pointer 
<-- 24 ioRefNum word 
--> 27 ioPermssn byte 


PBOpen opens the device driver specified by ioNamePtr, reading it into memory if 
necessary, and returns its reference number in ioRefNum. IOPermssn specifies the 
requested read/write permission. 


Result codes noErr No error 
badUnitErr Bad reference number 
diInstErr Couldn't find driver in resource file 
openErr Driver can't perform the requested 
reading or writing 
unitEmptyErr Bad reference number 


FUNCTION PBClose (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
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Trap macro _Close 


Parameter block 


--> 12 ioCompletion pointer 
<2. 16 ioResult word 
--> 24 ioRefNum word 


PBClose closes the device driver having the reference number ioRefNum. Any 
pending I/O is completed, and the memory used by the driver is released. 


Result codes noErr No error 
badUnitErr Bad reference number 
dRemovErr Attempt to remove an open driver 
unitEmptyErr Bad reference number 


FUNCTION PBRead (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _ Read 
eeeClick on the X-Ref button, and refer to Technical Note #187.¢ee 


Parameter block 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 

--> 22 ioVRefNum word 

--> 24 ioRefNum word 

--> 32 ioBuf fer pointer 
--> 36 ioReqCount long word 
<-- 40 ioActCount long word 
--> 44 ioPosMode word 


<-> 46 ioPosOffset long word 


PBRead attempts to read ioReqCount bytes from the device driver having the 
reference number ioRefNum, and transfer them to the data buffer pointed to by 
ioBuffer. The drive number, if any, of the device to be read from is specified 
by ioVRefNum. After the read is completed, the position is returned in 
ioPosOffset and the number of bytes actually read is returned in ioActCount. 


Result codes noErr No error 
badUnitErr Bad reference number 
notOpenErr Driver isn't open 
unitEmptyErr Bad reference number 
readErr Driver can't respond to Read calls 


FUNCTION PBWrite (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _Write 
eeeClick on the X-Ref button, and refer to Technical Note #187.¢e: 


Parameter block 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 22 ioVRefNum word 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
THE DEVICE MANAGER ¢ 16 of 62 


--> 24 ioRefNum word 


--> 32 ioBuffer pointer 
--> 36 ioReqCount long word 
<-- 40 ioActCount long word 
--> 44 ioPosMode word 


<-> 46 ioPosOffset long word 


PBWrite takes ioReqCount bytes from the buffer pointed to by ioBuffer and 
attempts to write them to the device driver having the reference number 
ioRefNum. The drive number, if any, of the device to be written to is specified 
by ioVRefNum. After the write is completed, the position is returned in 
ioPosOffset and the number of bytes actually written is returned in ioActCount. 


Result codes noErr No error 
badUnitErr Bad reference number 
notOpenErr Driver isn't open 
unitEmptyErr Bad reference number 
writErr Driver can't respond to Write calls 


FUNCTION PBControl (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _Control 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 22 ioVRefNum word 
--> 24 ioRefNum word 
--> 26 csCode word 
--> 28 csParam record 


PBControl sends control information to the device driver having the reference 
number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type 
of information sent is specified by csCode, and the information itself begins at 
csParam. The values passed in csCode and csParam depend on the driver being 
called. 


Result codes noErr No error 
badUnitErr Bad reference number 
notOpenErr Driver isn't open 
unitEmptyErr Bad reference number 
controlErr Driver can't respond to this Control call 


FUNCTION PBStatus (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _ Status 

Parameter block 
--> 12 ioCompletion pointer 
Fanae 16 ioResult word 
--> 22 ioVRefNum word 
--> 24 ioRefNum word 
--> 26 csCode word 
<-- 28 csParam record 
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PBStatus returns status information about the device driver having the reference 
number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type 
of information returned is specified by csCode, and the information itself 
begins at csParam. The values passed in csCode and csParam depend on the driver 
being called. 


Result codes noErr No error 
badUnitErr Bad reference number 
notOpenErr Driver isn't open 
unitEmptyErr Bad reference number 
statusErr Driver can't respond to this Status call 


FUNCTION PBKillLIO (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _KillIO 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 24 ioRefNum word 


PBKillLIO stops any current I/O request being processed, and removes all pending 
I/0 requests from the I/O queue of the device driver having the reference number 
ioRefNum. The completion routine of each pending I/O request is called, with the 
ioResult field of each request equal to the result code abortErr. 


Result codes noErr No error 
badUnitErr Bad reference number 
unitEmptyErr Bad reference number 
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THE STRUCTURE OF A DEVICE DRIVER 


This section describes the structure of device drivers for programmers 
interested in writing their own driver or manipulating existing drivers. Some of 
the information presented here is accessible only through assembly language. 


RAM drivers are stored in resource files. The resource type for drivers is 
'DRVR'. The resource name is the driver name. The resource ID for a driver is 
its unit number (explained below) and must be between 0 and 31 inclusive. 


Warning: Don't use the unit number of an existing driver unless you 
want the existing driver to be replaced. 


As shown in Figure 2, a driver begins with a few words of flags and other data, 
followed by offsets to the routines that do the work of the driver, an optional 
title, and finally the routines themselves. 


Every driver contains a routine to handle Open and Close calls, and may contain 
routines to handle Read, Write, Control, Status, and KillIO calls. The driver 
routines that handle Device Manager calls are as follows: 


Device Manager call Driver routine 

Open Open 

Read Prime 
Write Prime 
Control Control 
KilLIO Control 
Status Status 
Close Close 
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den Flags [word] 


For example, when a KillI0O 
routine must implement the 


Each bit of the high-order 


dReadEnable 
dwWritEnable 
dCtlEnable 
dStatEnable 
dNeedGoodBye 


dNeedTime 


dNeedLock 


. EQU 
. EQU 
. EQU 
. EQU 
. EQU 


. EQU 
. EQU 


dorHame + 1 [bytes] 


7 tems 


flags 
number of ticks betveen penodic actions 


desk accessory event mask 


men ID of menu associated with diver 


offset to open routine 
offset to prime routine 
offset to control routine 
offset to status routine 
offset to close routine 


length of diver name 


characters of diver name 


Figure 2-Diriver Structure 


BRWNF © 


Figure 2—-Driver Structure 


call is made to a driver, the driver's control 


call. 
byte of 


sset if 
sset if 
sset if 
sset if 
sset if 


the drvrFlags word contains a flag: 


driver 
driver 
driver 
driver 
driver 


can respond to Read calls 
can respond to Write calls 
can respond to Control calls 
can respond to Status calls 
needs to be called before 


; the application heap is reinitialized 

;set if driver needs time for performing 

; a periodic action 

;set if driver will be locked in memory as 

; soon as it's opened (always set for ROM drivers) 
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Bits 8-11 (bits 0-3 of the high-order byte) indicate which Device Manager calls 
the driver's routines can respond to. 


Unlocked RAM drivers in the application heap will be lost every time the heap is 
reinitialized (when an application starts up, for example). If dNeedGoodBye is 
set, the control routine of the device driver will be called before the heap is 
reinitialized, and the driver can perform any "clean-up" actions it needs to. 
The driver's control routine identifies this "good-bye" call by checking the 
csCode parameter—it will be the global constant 


goodBye .EQU -1 ;heap will be reinitialized, clean up if necessary 


Device drivers may need to perform predefined actions periodically. For example, 
a network driver may want to poll its input buffer every ten seconds to see if 
it has received any messages. If the dNeedTime flag is set, the driver does need 
to perform a periodic action, and the drvrDelay word contains a tick count 
indicating how often the periodic action should occur. A tick count of 0 means 
it should happen as often as possible, 1 means it should happen at most every 
sixtieth of a second, 2 means at most every thirtieth of a second, and so on. 
Whether the action actually occurs this frequently depends on how often the 
application calls the Desk Manager procedure SystemTask. SystemTask calls the 
driver's control routine (if the time indicated by drvrDelay has elapsed), and 
the control routine must perform whatever predefined action is desired. The 
driver's control routine identifies the SystemTask call by checking the csCode 
parameter—it will be the global constant 


accRun . EQU 65 ;take the periodic action, if any, for this driver 


Note: Some drivers may not want to rely on the application to call 
SystemTask. The Vertical Retrace Manager and Time Manager both offer 
the ability to perform tasks periodically. Both of these alternatives, 
however, perform these tasks at interrupt time, and there are certain 
restrictions on tasks performed during interrupts, such as not 
being able to make calls to the Memory Manager. For more information 
on these restrictions, see the Vertical Retrace Manager, and Time 
Manager chapters. Tasks that are time consuming may be able to take 
advantage of the Deferred Task Manager, which will allow other 
interrupts to be processed. Periodic actions performed in response to 
SystemTask calls are not performed via an interrupt and so don't have 
these restrictions. 


DrvrEMask and drvrMenu are used only for desk accessories and are discussed in 
the Desk Manager chapter. 


Following drvrMenu are the offsets to the driver routines, a title for the 
driver (preceded by its length in bytes), and the routines that do the work of 
the driver. 


Note: Each of the driver routines must be aligned on a word boundary. 


Device Control Entry 
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The first time a driver is opened, information about it is read into a structure 
in memory called a device control entry. A device control entry contains the 
header of the driver's I/O queue, the location of the driver's routines, and 
other information. A device control entry is a 40-byte relocatable block located 
in the system heap. It's locked while the driver is open, and unlocked while the 


driver is closed. 


Most of the data in the device control entry is stored and accessed only by the 
Device Manager, but in some cases the driver itself must store into it. The 
structure of a device control entry is shown below; note that the first four 
words of the driver are copied into the dCtlFlags, dCtlDelay, dCtlEMask, and 


dctlMenu fields. 


TYPE DCtlEntry = RECORD 
dcttDriver: 


dCtlFlags: 
dcttlQHdr: 


dCtlPosition: 


dctlStorage: 


dctlRefNum: 


dctlCurTicks: 


dCtlWindow: 
dctlDelay: 


dCtlEMask: 
dcttMenu: 


END; 


DCtlPtr 
DCtlHandle 


“DCtlEntry; 
“DCtLPtr; 


Ptr; 


INTEGER; 
QHdr; 
LONGINT; 


Handle; 


INTEGER; 
LONGINT; 
WindowPtr; 
INTEGER; 


INTEGER; 
INTEGER 


{pointer to ROM driver or } 
{ handle to RAM driver} 
{flags} 

{driver I/0 queue header} 
{byte position used by Read } 
{ and Write calls} 

{handle to RAM driver's } 

{ private storage} 

{driver reference number} 
{used internally} 

{pointer to driver's window} 
{number of ticks between } 

{ periodic actions} 

{desk accessory event mask} 
{menu ID of menu associated 
{ with driver} 


The low-order byte of the dCtlFlags word contains the following flags: 


Bit number Meaning 
5 Set if driver is open 
6 Set if driver is RAM-based 
7 Set if driver is currently executing 


Assembly- language note: 


These flags can be accessed with the global 


constants dOpened, dRAMBased, and drvrActive. 


The high-order byte of the dCtlFlags word contains flags copied from the 
drvrFlags word of the driver, as described above. 


DCtlQHdr contains the header of the driver's I/O queue (described below). 
DCtlPosition is used only by drivers of block devices, and indicates the current 
source or destination position of a Read or Write call. The position is given as 
a number of bytes beyond the physical beginning of the medium used by the 
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device. For example, if one logical block of data has just been read from a 3 
1/2-inch disk via the Disk Driver, dCtlPosition will be 512. 


ROM drivers generally use locations in low memory for their local storage. RAM 
drivers may reserve memory within their code space, or allocate a relocatable 
block and keep a handle to it in dCtlStorage (if the block resides in the 
application heap, its handle will be set to NIL when the heap is reinitialized). 


You can get a handle to a driver's device control entry by calling the Device 
Manager function GetDCtlEntry. 


FUNCTION GetDCtlEntry (refNum: INTEGER) : DCtlHandle; [Not in ROM] 


GetDCtlEntry returns a handle to the device control entry of the device driver 
having the reference number refNum. 


Assembly-language note: You can get a handle to a driver's device control 
entry from the unit table, as described below. 


The Driver I/0 Queue 


Each device driver has a driver I/O queue; this is a standard Operating System 
queue (described in the Operating System Utilities chapter) that contains the 
parameter blocks for all asynchronous routines awaiting execution. Each time a 
routine is called, the driver places an entry in the queue; each time a routine 
is completed, its entry is removed from the queue. The queue's header is located 
in the dCtlQHdr field of the driver's device control entry. The low-order byte 
of the queue flags field in the queue header contains the version number of the 
driver, and can be used for distinguishing between different versions of the 
same driver. 


Each entry in the driver I/0 queue consists of a parameter block for the routine 
that was called. Most of the fields of this parameter block contain information 
needed by the specific Device Manager routines; these fields are explained above 
in the section "Low-Level Device Manager Routines". The first four fields of 
this parameter block, shown below, are used by the Device Manager in processing 
the I/0 requests in the queue. 


TYPE ParamBlockRec = RECORD 


qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
ioTrap: INTEGER; {routine trap} 


ioCmdAddr: Ptr; {routine address} 
ayer ak {rest of block} 
END; 


QLink points to the next entry in the queue, and qlype indicates the queue type, 
which must always be ORD(ioQType). IOTrap and ioCmdAddr contain the trap and 
address of the Device Manager routine that was called. 
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The Unit Table 


The location of each device control entry is maintained in a list called the 
unit table. The unit table is a 128-byte nonrelocatable block containing 32 
four-byte entries. Each entry has a number, from 0 to 31, called the unit 
number, and contains a handle to the device control entry for a driver. The unit 
number can be used as an index into the unit table to locate the handle to a 
specific driver's device control entry; it's equal to 


—1 * (refNum + 1) 


where refNum is the driver reference number. For example, the Sound Driver's 
reference number is —4 and its unit number is 3. 


Figure 3 shows the layout of the unit table with the standard drivers and desk 
accessories installed. 
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Warning: 


om oe 
«Tawar | 
[etm | 


124 31 


Figure 3-The Unit Table 
Figure 3—The Unit Table 


Any new drivers contained in resource files should have resource 
IDs that don't conflict with the unit numbers of existing 
drivers—unless you want an existing driver to be replaced. Be 
sure to check the unit table before installing a new driver; 

the base address of the unit table is stored in the global 
variable UTableBase. 
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eeeClick on the X-Ref button, and refer to Technical Note #71.+¢ee 
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WRITING YOUR OWN DEVICE DRIVERS 


Drivers are usually written in assembly language. The structure of your driver 
must match that shown in the previous section. The routines that do the work of 
the driver should be written to operate the device in whatever way you require. 
Your driver must contain routines to handle Open and Close calls, and may choose 
to handle Read, Write, Control, Status, and KillIO calls as well. 


Warning: A device driver doesn't "own" the hardware it operates, and has 
no way of determining whether another driver is attempting to 
use that hardware at the same time. There's a possiblity of 
conflict in situations where two drivers that operate the same 
device are installed concurrently. 


When the Device Manager executes a driver routine to handle an application call, 
it passes a pointer to the call's parameter block in register AQ and a pointer 
to the driver's device control entry in register Al. From this information, the 
driver can determine exactly what operations are required to fulfill the call's 
requests, and do them. 


Open and close routines must execute synchronously and return via an RTS 
instruction. They needn't preserve any registers that they use. Close routines 
should put a result code in register DQ. Since the Device Manager sets DO to 0 
upon return from an Open call, open routines should instead place the result 
code in the ioResult field of the parameter block. 


The open routine must allocate any private storage required by the driver, store 
a handle to it in the device control entry (in the dCtlStorage field), 
initialize any local variables, and then be ready to receive a Read, Write, 
Status, Control, or KillIO call. It might also install interrupt handlers, 
change interrupt vectors, and store a pointer to the device control entry 
somewhere in its local storage for its interrupt handlers to use. The close 
routine must reverse the effects of the open routine, by releasing all used 
memory, removing interrupt handlers, and replacing changed interrupt vectors. If 
anything about the operational state of the driver should be saved until the 
next time the driver is opened, it should be kept in the relocatable block of 
memory pointed to by dCtlStorage. 


Prime, control, and status routines must be able to respond to queued calls and 
asynchronous calls, and should be interrupt-driven. Asynchronous portions of the 
routines can use registers AQ-A3 and DO-D3, but must preserve any other 
registers used; synchronous portions can use all registers. Prime, control, and 
status routines should return a result code in DO. They must return via an RTS 
if called immediately (with noQueueBit set in the ioTrap field) or if the device 
couldn't complete the I/O request right away, or via a JMP to the I0Done routine 
(explained below) if not called immediately and if the device completed the 
request. 


Warning: If the prime, control, and status routines can be called as the 
result of an interrupt, they must preserve all registers other 
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than AO, Al, and DO-D2. They can't make any calls to the Memory 
Manager and cannot depend on unlocked handles being valid. If 
they use application globals, they must also ensure that register 
A5 contains the address of the boundary between the application 
globals and the application parameters; for details, refer to 
SetCurrentA5 and SetA5 in Macintosh Technical Note #208. 


eeeClick on the X-Ref button, and refer to Technical Note #208.¢ee 


The prime routine implements Read and Write calls made to the driver. It can 
distinguish between Read and Write calls by comparing the low-order byte of the 
ioTrap field with the following predefined constants: 


aRdCmd . EQU 2 »Read call 
aWrCmd . EQU 3 ‘Write call 


You may want to use the Fetch and Stash routines (described below) to read and 
write characters. If the driver is for a block device, it should update the 
dCtlPosition field of the device control entry after each read or write. 


The control routine accepts the control information passed to it, and 
manipulates the device as requested. The status routine returns requested status 
information. Since both the control and status routines may be subjected to 
Control and Status calls sending and requesting a variety of information, they 
must be prepared to respond correctly to all types. The control routine must 
handle KillIO calls. The driver identifies KillIO calls by checking the csCode 
parameter—it will be the global constant 


killCode . EQU 1 shandle the KillLIO call 


Warning: KillIO calls must return via an RTS, and shouldn't jump 
(via JMP) to the I0Done routine. 


Routines for Writing Drivers 


The Device Manager includes three routines—Fetch, Stash, and I0Done—that provide 
low-level support for driver routines. These routines can be used only with a 
pending, asynchronous request; include them in the code of your device driver if 
they're useful to you. A pointer to the device control entry is passed to each 
of these routines in register Al. The device control entry contains the driver 
I/O queue header, which is used to locate the pending request. If there are no 
pending requests, these routines generate the system error dsIOCoreErr (see the 
System Error Handler chapter for more information). 


eeeClick on the X-Ref button, and refer to Technical Notes #36, #108, & 187.¢e¢e 
eeeClick on the X-Ref button, and refer to Technical Note #257 & Q & A Stack.eee 


Fetch, Stash, and I0Done are invoked via "jump vectors" (stored in the global 
variables JFetch, JStash, and JIODone) rather than macros, in the interest of 
speed. You use a jump vector by moving its address onto the stack. For example: 


MOVE.L JIODone, - (SP) 
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RTS 


Fetch and Stash don't return a result code; if an error occurs, the System Error 
Handler is invoked. I0Done may return a result code. 


Fetch function 


Jump vector JFetch 

On entry Al: pointer to device control entry 

On exit DO: character fetched; bit 15=1 if it's the last 
character in data buffer 


Fetch gets the next character from the data buffer pointed to by ioBuffer and 
places it in DQ. I0ActCount is incremented by 1. If ioActCount equals 
ioReqCount, bit 15 of DO is set. After receiving the last byte requested, the 
driver should call I0Done. 

Stash function 


Jump vector JStash 


On entry Al: pointer to device control entry 
DO: character to stash 
On exit DO: bit 15=1 if it's the last character requested 


Stash places the character in DO into the data buffer pointed to by ioBuffer, 
and increments ioActCount by 1. If ioActCount equals ioReqCount, bit 15 of DO is 
set. After stashing the last byte requested, the driver should call I0Done. 


I0Done function 


Jump vector JI0Done 
On entry Al: pointer to device control entry 
DO: result code (word) 


IODone removes the current I/O request from the driver I/O queue, marks the 
driver inactive, unlocks the driver and its device control entry (if it's 
allowed to by the dNeedLock bit of the dCtlFlags word), and executes the 
completion routine (if there is one). Then it begins executing the next I/0 
request in the driver I/0 queue. 


Warning: Due to the way the File Manager does directory lookups, block 
device drivers should take care to support asynchronous I/0 
operations. If the driver's prime routine has completed an 
asynchronous Read or Write call just prior to calling I0Done 
and its completion routine starts an additional Read or Write, 
large amounts of the stack may be used (potentially causing the 
stack to expand into the heap). To avoid this problem, the prime 
routine should exit via an RTS instruction and then jump to I0Done 
via an interrupt. 
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INTERRUPTS 


This section discusses how interrupts are used on the Macintosh 128K and 512K 
specifically. The general philosophy applies to all Macintosh computers. Only 
programmers who want to write interrupt-driven device drivers need read this 
section. 


Warning: Only the Macintosh 128K and 512K are covered in this section. 
Much of the information presented here is hardware-dependent; 
programmers are encouraged to write code that's hardware-independent 
to ensure compatibility with future versions of the Macintosh. 


An interrupt is a form of exception: an error or abnormal condition detected by 
the processor in the course of program execution. Specifically, an interrupt is 
an exception that's signaled to the processor by a device, as distinct from a 
trap, which arises directly from the execution of an instruction. Interrupts are 
used by devices to notify the processor of a change in condition of the device, 
such as the completion of an I/O request. An interrupt causes the processor to 
suspend normal execution, save the address of the next instruction and the 
processor's internal status on the stack, and execute an interrupt handler. 


The MC68000 recognizes seven different levels of interrupt, each with its own 
interrupt handler. The addresses of the various handlers, called interrupt 
vectors, are kept in a vector table in low memory. Each level of interrupt has 
its own vector located in the vector table. When an interrupt occurs, the 
processor fetches the proper vector from the table, uses it to locate the 
interrupt handler for that level of interrupt, and jumps to the handler. On 
completion, the handler restores the internal status of the processor from the 
stack and resumes normal execution from the point of suspension. 


There are three devices that can create interrupts: the Synertek SY6522 
Versatile Interface Adapter (VIA), the Zilog Z8530 Serial Communications 
Controller (SCC), and the debugging switch. They send a three-bit number called 
the interrupt priority level to the processor. This number indicates which 
device is interrupting, and which interrupt handler should be executed: 


Level Interrupting device 


None 
VIA 
SCC 
VIA and SCC 
-7 Debugging switch 


BWNF © 


A level-3 interrupt occurs when both the VIA and the SCC interrupt at the same 
instant; the interrupt handler for a level-3 interrupt is simply an RTE 
instruction. Debugging interrupts shouldn't occur during the normal execution of 
an application. 


The interrupt priority level is compared with the processor priority in bits 
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8-10 of the status register. If the interrupt priority level is greater than the 
processor priority, the MC68000 acknowledges the interrupt and initiates 
interrupt processing. The processor priority determines which interrupting 
devices are ignored, and which are serviced: 


Level Services 
0 ALL interrupts 
1 SCC and debugging interrupts only 
2-6 Debugging interrupts only 
7 No interrupts 


When an interrupt is acknowledged, the processor priority is set to the 
interrupt priority level, to prevent additional interrupts of equal or lower 
priority, until the interrupt handler has finished servicing the interrupt. 


The interrupt priority level is used as an index into the primary interrupt 
vector table. This table contains seven long words beginning at address $64. 
Each long word contains the starting address of an interrupt handler (see Figure 


4). 


Execution jumps to the interrupt handler at the address specified in the table. 
The interrupt handler must identify and service the interrupt. Then it must 
restore the processor priority, status register, and program counter to the 
values they contained before the interrupt occurred. 


$64 
$68 
$6c 
$70 
$74 
$75 
$70 


Antolntl 


Antolin 


Amtolnat 


Antolnt 
Antoint 
Antolin 


Antolnt? 


vector to level-1 intermupt handler 


vector to level-2 interrupt handler 


vector to level-3 interupt handler 


vector to level-4 intemupt handler 


vector to level-5 intemupt handler 


vector to level-6 interrupt handler 


vector to level-7 interrupt handler 


Figure 4—Primary Interrupt Yector Table 


Figure 4—Primary Interrupt Vector Table 


Level-1 (VIA) Interrupts 
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Level-1 interrupts are generated by the VIA. You'll need to read the Synertek 
manual describing the VIA to use most of the information provided in this 
section. The level-1 interrupt handler determines the source of the interrupt 
(via the VIA's interrupt flag register and interrupt enable register) and then 
uses a table of secondary vectors in low memory to determine which interrupt 
handler to call (see Figure 5). 


byte Va's CA2 contol in 
: Via's CAL contol lin 
5 VA's shift resister 
2 

: 

: 


Figure 5—Level-1 Secondary Interrupt Yector Table 


Figure 5—Level-1 Secondary Interrupt Vector Table 


The level-1 secondary interrupt vector table is stored in the global variable 
Lvl1DT. Each vector in the table points to the interrupt handler for a different 
source of interrupt. The interrupts are handled in order of their entry in the 
table, and only one interrupt handler is called per level-1 interrupt (even if 
two or more sources are interrupting). This allows the 

level-1 interrupt handler to be reentrant; interrupt handlers should lower the 
processor priority as soon as possible in order to enable other pending 
interrupts to be processed. 


The one-second interrupt updates the global variable Time (explained in the 
Operating System Utilities chapter); it's also used for inverting ("blinking") 
the apple symbol in the menu bar when the alarm goes off. Vertical retrace 
interrupts are generated once every vertical retrace interval; control is passed 
to the Vertical Retrace Manager, which performs recurrent system tasks 

(such as updating the global variable Ticks) and executes tasks installed by the 
application. (For more information, see the Vertical Retrace Manager chapter. ) 


If the cumulative elapsed time for all tasks during a vertical retrace interrupt 
exceeds about 16 milliseconds (one video frame), the vertical retrace interrupt 
may itself be interrupted by another vertical retrace interrupt. In this case, 
tasks to be performed during the second vertical retrace interrupt are ignored, 
with one exception: The global variable Ticks will still be updated. 
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The shift-register interrupt is used by the keyboard and mouse interrupt 
handlers. Whenever the Disk Driver or Sound Driver isn't being used, you can use 
the Tl and T2 timers for your own needs; there's no way to tell, however, when 
they'll be needed again by the Disk Driver or Sound Driver. 


The base address of the VIA (stored in the global variable VIA) is passed to 
each interrupt handler in register Al. 


Level-2 (SCC) Interrupts 


Level-2 interrupts are generated by the SCC. You'll need to read the Zilog 
manual describing the SCC to effectively use the information provided in this 
section. The level-2 interrupt handler determines the source of the interrupt, 
and then uses a table of secondary vectors in low memory to determine which 
interrupt handler to call (see Figure 6). 


ved 
noe vet 
: 

2 

: 

: 

. 


Figure 6—-Levrel-2 Secondary Interrupt Fector Table 


Figure 6—Level-2 Secondary Interrupt Vector Table 


The level-2 secondary interrupt vector table is stored in the global variable 
Lvl2DT. Each vector in the table points to the interrupt handler for a different 
source of interrupt. The interrupts are handled according to the following fixed 
priority: 


channel A receive character available and special receive 
channel A transmit buffer empty 
channel A external/status change 
channel B receive character available and special receive 
channel B transmit buffer empty 

B 


channel B external/status change 
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Only one interrupt handler is called per level-2 interrupt (even if two or more 
sources are interrupting). This allows the level-2 interrupt handler to be 
reentrant; interrupt handlers should lower the processor priority as soon as 
possible in order to enable other pending interrupts to be processed. 


External/status interrupts pass through a tertiary vector table in low memory to 
determine which interrupt handler to call (see Figure 7). 


channel B communications interupt 
mouse vertical interrupt 


channel A communications interrupt 
mouse horizontal interupt 


Figure 7—Level 2-ExternallStatus Yector Table 


Figure 7—Level-2 External/Status Interrupt Vector Table 


The external/status interrupt vector table is stored in the global variable 
ExtStsDT. Each vector in the table points to the interrupt handler for a 
different source of interrupt. Communications interrupts (break/abort, for 
example) are always handled before mouse interrupts. 


When a level-2 interrupt handler is called, DO contains the address of the SCC 
read register 0 (external/status interrupts only), and Dl contains the bits of 
read register 0 that have changed since the last external/status interrupt. AQ 
points to the SCC channel A or channel B control read address and Al points to 
SCC channel A or channel B control write address, depending on which channel is 
interrupting. The SCC's data read address and data write address are located 
four bytes beyond AO and Al, respectively; they're also contained in the global 
variables SCCWr and SCCRd. You can use the following predefined constants as 
offsets from these base addresses to locate the SCC control and data lines: 


aData . EQU 6 schannel A data in or out 
aCtl . EQU 2 ‘channel A control 
bData . EQU 4 ‘channel B data in or out 
bCtl . EQU 0 »channel B control 


Writing Your Own Interrupt Handlers 

You can write your own interrupt handlers to replace any of the standard 
interrupt handlers just described. Be sure to place a vector that points to your 
interrupt handler in one of the vector tables. 


Both the level-1 and level-2 interrupt handlers preserve registers AQ-A3 and 
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DO-D3. Every interrupt handler (except for external/status interrupt handlers) 
is responsible for clearing the source of the interrupt, and for saving and 
restoring any additional registers used. Interrupt handlers should return 
directly via an RTS instruction, unless the interrupt is completing an 


asynchronous call, in which case they should jump (via JMP) to the I0Done 
routine. 
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THE CHOOSER 


Note: The extensions to the Device Manager described in the following 
section were originally documented in Inside Macintosh, Volume IV. 
As such, this information refers to the 128K ROMs and System file 
version 3.2 and later. 


The Chooser is a desk accessory that provides a standard interface to help 
solicit and accept specific choices from the user. It allows new device drivers 
to prompt the user for choices such as which serial port to use, which AppleTalk 
zone to communicate with, and which LaserWriter to use. 


The Chooser relies heavily on the List Manager for creating, displaying, and 
manipulating possible user selections. The List Manager is described in the List 
Manager chapter. 


Under the Chooser, each device is represented by a device resource file in the 
system folder on the user's system startup disk. (This is an extension of the 
concept of printer resource files, described in the Printing Manager chapter. ) 
The Chooser accepts three types of device resource files to identify different 
kinds of devices: 


File type Device type 


"PRES ' Serial printer 
"PRER' Non-serial printer 
"RDEV' Other device 


The creator of each file is left undefined, allowing each device to have its own 
icon. 


In addition to any actual driver code, each device resource file of type 'PRER' 
or 'RDEV' contains a set of resources that tell the Chooser how to handle the 
device. These resources include: 


Resource type Resource ID Description 

"PACK' —4096 Device package (described below) 

‘STR ' —4096 Type name for AppleTalk devices 

"GNRL' —4096 NBP timeout and retry information 
for AppleTalk devices 

‘STR ' —4093 Left button title 

‘STR ' —4092 Right button title 

'STR ' —4091 String for Chooser to use to label 
the list when choosing the device 

"BNDL ' Icon information 

‘STR '' —4090 Reserved for use by the Chooser 


Warning: You should give your device type a distinctive icon, since this 
may be the only way that devices are identified in the Chooser's 
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screen display. 


Device resource files of type 'PRES' (serial printers) contain only the driver 
code, without any of the resources listed above. The configuration of such 
devices is implemented entirely by the Chooser. 


The Device Package 


The device package is usually written in assembly language, but may be written 
partially in Pascal. The assembly-language structure of the 'PACK' —4096 
resource is as follows: 


Offset (hex) Word 


BRA.S to offset $10 
Device ID (word) 
'PACK' (long word) 
$FO00 (—4096) 
Version (word) 
Flags (long word) 

0 Start of driver code 


FPOAPrARNO® 


The device ID is an integer that identifies the device. The version word 
differentiates versions of the driver code. The flags field contains the 
following information: 


Bit Meaning 

31 Set if an AppleTalk device 

30-29 Reserved (clear to 0) 

28 Set if device package can have multiple instances selected at once 
27 Set if device package uses left button 

26 Set if device package uses right button 

25 Set if no saved zone name 

24 Set if device package uses actual zone names 

23-17 Reserved (clear to 0) 

16 Set if device package accepts the newSel message 

15 Set if device package accepts the fillList message 
14 Set if device package accepts the getSel message 

13 Set if device package accepts the select message 

12 Set if device package accepts the deselect message 
11 Set if device package accepts the terminate message 


10-0 Reserved (clear to 0) 


Communication with the Chooser 


The Chooser communicates with device packages as if they were the following 
function: 


FUNCTION Device (message,caller: INTEGER; objName,zoneName: StringPtr; 
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pl,p2: LONGINT) : OSErr; 


The message parameter identifies the operation to be performed. It has one of 
the following values: 


CONST newSelMsg = 12; {new user selections have been made} 
FillListMsg = 13; {fill the list with choices to be made} 
getSelMsg = 14; {mark one or more choices as selected} 
selectMsg = 15; {a choice has actually been made} 
deselectMsg = 16; {a choice has been cancelled} 
terminateMsg = 17; {lets device package clean up}} 
buttonMsg = 19; {tells driver a button has been selected} 


The device package should always return noErr, except with select and deselect; 
with these messages, a result code other than noErr prevents selection or 
deselection from occurring. The device package must ignore any other messages in 
the range 0..127 and return noErr. If the message is selectMsg or deselectMsg, 
it may not call the List Manager. 


The caller parameter identifies the caller as the Chooser, with a value of 1. 
Values in the range 0..127 are reserved; values outside this range may be used 
by applications. 


For AppleTalk devices, the zoneName parameter is a pointer to a string of up to 
32 characters containing the name of the AppleTalk zone in which the devices can 
be found. If the Chooser is being used with the local zone and bit 24 of the 
Flags field of the 'PACK' —4096 resource is clear, the string value is '*'; 
otherwise it's the actual zone name. 

The pl parameter is a handle to a List Manager list of choices for a particular 
device; this device list must be filled by the device package in response to the 
fillListMsg message. 

Other details of the Chooser messages and their parameters are given below. 

The NewSelMsg Parameter 

The Chooser sends the newSel message (instead of the select or deselect message) 
only to device packages that allow multiple selections, when the user changes 
the selection. 

The objName and p2 parameters are not used. 

The FillListMsg Parameter 

When the Chooser sends the fillList message, the device package should fill a 
List Manager list filled with choices for a particular device; the pl parameter 
is a handle to this list. 

The objName and p2 parameters are not used. 


The GetSelMsg Parameter 
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When the Chooser sends the getSel message the device package should mark one or 
more choices in the given list as currently selected, by a call to LSetSelect. 


The objName and p2 parameters are not used. 
The SelectMsg Parameter 


The Chooser sends the select message whenever a particular choice has become 
selected, but only to device packages that do not allow multiple selections. The 
device package may not call the List Manager. 


If the device accepts fillList messages, objName is undefined. Otherwise, the 
objName parameter is a pointer to a string of up to 32 characters containing the 
name of the device. 


If the device accepts fillList messages, p2 gives the row number of the list 
that has become selected; otherwise (if the device is an AppleTalk device) p2 
gives the AddrBlock value for the address of the AppleTalk device that has just 
become selected. 


The DeselectMsg Parameter 


The Chooser sends the deselect message whenever a particular choice has become 
deselected, but only to device packages that do not allow multiple selections. 
The device package may not call the List Manager. 


If the device accepts fillList messages, objName is undefined. Otherwise, the 
objName parameter is a pointer to a string of up to 32 characters containing the 
name of the device. 


If the device accepts fillList messages, p2 gives the row number of the list 
that has become deselected; otherwise (if the device is an AppleTalk device) p2 
gives the AddrBlock value for the address of the AppleTalk device that has just 
become deselected. 

The TerminateMsg Parameter 

The Chooser sends the terminate message when the user selects a different device 
icon, closes the Chooser window, or changes zones. It allows the device package 
to perform cleanup tasks, if necessary. The device package should not dispose of 
the device list. 

The objName and p2 parameters are not used. 

The ButtonMsg Parameter 


The Chooser sends the button message when a button in the Chooser display has 
been clicked. 


The low-order byte of the p2 parameter has a value of 1 if the left button has 
been clicked and 2 if the right button has been clicked. 


The objName parameter is not used. 
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Operation of the Chooser 


When the Chooser is first selected from the desk accessory menu, it searches the 
system folder of the startup disk for device resource files—that is, resource 
files of type 'PRER', 'PRES', or 'RDEV'. For each one that it finds, it opens 
the file, fetches the device's icon, fetches the flags long word from the device 
package, and closes the file. The Chooser then takes the following actions for 
each device, based on the information just retrieved: 


e It displays the device's icon in the Chooser's window. 
e If the device is an AppleTalk device and AppleTalk is not connected, 
the Chooser grays the device's icon. 


When the user selects a device icon that is not grayed, the Chooser reopens the 
corresponding device resource file. It then does the following: 


e If the device is type 'PRER' or 'PRES', it sets the current 
printer type to that device. 


e It labels the device's list box with the string in the resource 
'STR ' with an ID of —4091. 


e If the device is a local printer, the Chooser fills its list box 
with the two icons for the printer port and modem port serial drivers. 
Later it will record the user's choice in low memory and parameter RAM. 


e If the device accepts fillList messages, the Chooser calls the device 
package, which should fill column 0 of the list pointed to by pl with 
the names (without length bytes) of all available devices in the zone. 


e If the device is an AppleTalk device that does not accept fillList 
messages, the Chooser initiates an asynchronous routine that interrogates 
the current AppleTalk zone for all devices of the type specified in the 
device's resource 'STR ' —4096. The NBP retry interval and count are 
taken from the 'GNRL' resource —4096; the format of this resource 
consists one byte for the interval followed by another byte for the 
count. AS responses arrive, the Chooser updates the list box. 


¢ To determine which list choices should be currently selected, the 
Chooser calls the device with the getSel message. The device code 
should respond by inspecting the list and setting the selected/unselected 
state of each entry. The Chooser may make this call frequently; for 
example, each time a new response to the AppleTalk zone interrogation 
arrives. Hence the device should alter only those entries that need 
changing. This procedure is not used with serial printers; for them, 
the Chooser just accesses low memory. 


e The Chooser checks the flag in the 'PACK' —4096 resource that indicates 
whether multiple devices can be active at once, and sets List Manager 
bits accordingly. Whenever the user selects or deselects a device, the 
Chooser will call the device package with the appropriate message (if 
it's accepted). For packages that do not accept multiple active devices, 
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this is the select or deselect message; otherwise it's the newSel message. 
The device code should implement both mounting and unmounting the device, 
if appropriate, and recording the user's selections on disk, preferably 
in the device resource file (which is the current resource file). 


When the Chooser is deactivated, it calls the UpdateResFile procedure on the 
device resource file and flushes the system startup volume. 


When the user chooses a different device type icon or closes the Chooser, the 
Chooser will call the device with the terminate message (if it's accepted). This 
allows device packages to clean up, if necessary. After this check, the Chooser 
closes the device resource file (if the device is not the current printer) and 
flushes the system startup volume. 


Writing a Device Driver to Run Under Chooser 


The code section of a driver running under chooser is contained in the 'PACK' 
—4096 resource, as explained earlier. The driver structure remains as described 
earlier in this chapter. 


Device packages initially have no data space allocated. There are two ways to 
acquire data space for a device package: 


e Use the List Manager 
« Create a resource 


These options are discussed below. 


The best method is to call the List Manager. The Chooser uses column 0 of the 
device list to store the names displayed in the list box. If the device package 
currently in use does not accept fillList messages, column 1 stores the four- 
byte AppleTalk internet addresses of the entities in the list. Therefore, the 
device package can use column 1 and higher (if it accepts fillList) or column 2 
and higher to store data private to itself. The standard List Manager calls can 
be used to add these columns, place data in them, and retrieve data stored 
there. 


eeeClick on the X-Ref button, and refer to Technical Note #250. eee 


There are several restrictions on data storage in List Manager cells. The list 
is disposed whenever : 


« the user changes device types. 

e the user changes the current zone. 

e the device package does not accept fillList messages, and a new 
response to the AppleTalk zone interrogation arrives. The device 
package will be called with the getSel message immediately afterwards. 


When either of the first two situations occurs, the device package is called 
with the terminate message before the list is disposed. 
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Another way to get storage space is to create a resource in the device's file. 
This file is always the current resource file when the package is called; 
therefore it can issue GetResource calls to get a handle to its storage. 


It is important for most device packages to record which devices have been 
chosen. To do this, the recommended method is to create a resource in the 
resource file. This resource can be of any type; it fact, it's advantageous to 
provide your own resource type so that no other program will try to access it. 
If you choose to use a standard resource type, you should use only resource IDs 
in the range —4080 to —4065. 


Note: The extensions to the Device Manager described in the following 
paragraphs were originally documented in Inside Macintosh, Volume V. 
As such, this information refers to the Macintosh SE and Macintosh II 
ROMs and System file version 4.1 and later. 


Chooser Changes 


Note: The extensions to the Device Manager described in the following 
paragraphs were originally documented in Inside Macintosh, Volume V. 
As such, this information refers to the Macintosh SE and Macintosh II 
ROMs and System file version 4.1 and later. 


Three new facilities for user-written device packages have been added to the 
Chooser: 


e In addition to specifying and setting their names, a device package 
can now position one or both buttons. 

e A device package can now supply a custom list definition for the 
device list. The custom list can include icons, pictures, or small 
icons next to the name. 

¢ Applications that do their own housekeeping can now bypass the 
warning message brought up whenever a different device is chosen. 


Figure 8 shows the new window displayed by the Chooser. 
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Figure §-The Chooser Window 


Figure 8—The Chooser Window 


As described elsewhere in this chapter, the Chooser can also prompt the user for 
which AppleTalk network zone to communicate with. See Figure 9. 
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Figure 9-The Chooser Displaying Zones 


Figure 9-The Chooser Displaying Zones 
Buttons 


A device package can choose to have 0, 1, or 2 buttons, as determined by bits 27 
and 26 in the flag field of the device ID. The two buttons are not the same. 
The button set by bit 27 is called the Left Button, and the button set by bit 26 
the Right Button, because these are their default positions. 


The Left Button has a double border, and if it is highlighted (the title string 
is dark, not gray), then a Return, Enter, or double click are equivalent to 
clicking the button. The Left Button is highlighted only when one or more 
devices are selected in the device list. The Right Button has a single border, 
never dims its title, and can be activated only by clicking it. 


Buttons can be positioned by having a resource type 'nrct' with an ID of —4096 
in the device file. The first word of the resource is the number of rectangles 
in the list, in this case two; the rest of the resource contains the rectangle 
definitions. The first rectangle is the Left Button, the second is the Right 
Button. 


Each rectangle definition is eight bytes long and contains the rectangle 
coordinates in the order [top, left, bottom, right] order. The default values 
are [112, 206, 132, 266] for the Left Button, and [112, 296, 132, 356] for the 
Right Button. Substituting 'nrct' values of [112, 251, 132, 311], for example, 
would center a single button. 
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There's an additional button-related change: in the ButtonMsg parameter, the 
low order byte of the P2 parameter has a value of 1 or 2 depending on whether 
the Left Button or Right Button was clicked. The high order word of P2 now 
contains modifier bits from the event.List Definition Procedure 


The Chooser uses the List Manager to produce and display the standard device 
list. The programmer can now supply a list definition procedure, which could, 
for example, include pictures or icons. The application should provide an 
'LDEF' resource with an ID of —4096. 


Also, with Chooser 3.0 and above the device may use the refCon field of the 
device list for its own purposes. Remember that the list will be disposed of 
whenever the user changes device types or changes the current zone. 


Before the list is disposed of, the device package will be called with the 
terminate message. 


See the List Manager chapter for the mechanics of list construction and the list 
record data structure. 


Page Setup 


The Chooser normally issues a warning message whenever a different printer type 
is selected: 


Be sure to choose Page Setup and confirm the settings so that 
the application can format documents correctly for the <printer>. 


Since some applications handle the page resetup correctly on their own, the 
Chooser now offers a way for applications to bypass the message. 


FUNCTION SetChooserAlert (f:BOOLEAN) : BOOLEAN; 


If f is true, the Chooser will put up the page setup alert; if f is false it 
won't. SetChooserAlert returns the original alert state. The application 
should restore the original alert state when it exits. 


Assembly-language note: If the psAlert bit of the low-memory global 
HiliteMode is 0 then no page setup alert will be 
generated. Applications that set or clear this 
bit must be sure not to affect any other bits in 
the byte and to restore the bit as they leave. 


HiliteMode equ $938 


psAlert equ 6 
bclr #psAlert,HiliteMode 
bset #psAlert,HiliteMode 


Device Package Function 


When the device package is called, the device file will be the current resource 
file, the Chooser's window will be the current grafPort, and the System Folder 
of the current startup disk will be the default volume. The device package must 
preserve all of these. 
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THE STARTUP PROCESS 


Note: The extensions to the Device Manager described in the following 
sections were originally documented in Inside Macintosh, Volume V. 
As such, this information refers to the Macintosh SE and Macintosh II 
ROMs and System file version 4.1 and later. 


The Macintosh II ROM searches for the startup device using an algorithm 
described in the Start Manager chapter. It will attempt to start from a NuBus 
card only when certain values are set in its parameter RAM. These values can be 
accessed by using Start Manager routines. 


When the Macintosh starts up from a card in a NuBus slot, it uses startup code 
found in an sResource in the configuration ROM on the card. Otherwise, the 
normal Macintosh startup process occurs. Configuration ROMs and sResources are 
described in the Slot Manager chapter and in the book "Designing Cards and 
Drivers for Macintosh II and Macintosh SE." 


If parameter RAM specifies a valid sResource ID and slot, and if that sResource 
has an sBootRecord, it is used for startup. The ROM loads the slot startup code 
into memory and calls its entry point to execute it. For non-Macintosh 
operating systems that take over the machine, this code is either the operating 
system itself or a startup program. For instance, a traditional UNIX® startup 
process would bring in the secondary startup program, which prompts for a device 
name or filename to execute. The ROM would never receive control again. 


The sBootRecord code is first called early in the ROM-based startup sequence, 
before any access to the internal drive. It is passed an seBlock pointed to by 
register AO. If a non-Macintosh operating system is being installed, the 
sBootRecord can pass control to it. In this case, control never returns to the 
normal start sequence in the Macintosh ROM. 


When the Macintosh operating system is started up, the sBootRecord is called 
twice. The first time, when the value of seBootState is 0, the startup code 
tries to load and open at least one driver for the card-based device and install 
it in the disk drive queue. It returns the refnum of the driver. That driver 
becomes the initial one used to install the Macintosh operating system. During 
the second call to the sBootRecord (when the value of seBootState is 1), which 
happens after system patches have been installed but before 'INIT' resources 
have been executed, the sBootRec must open any remaining drivers for devices on 
the card. 


The sBootRecord can use the HOpen call to open the driver and install it into 
the unit table. The HOpen call will either fetch the driver from the sDriver 
directory, or call the sLoadDriver record if one exists. In any case, the 
driver's open code must install the driver into the drive queue. This process 
is discussed in more detail in the Card Firmware chapter of the book "Designing 
Cards and Drivers for Macintosh II and Macintosh SE." 
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Automatic Driver Installation 


During the startup process the system installs the default video and startup 
drivers, as described in the Start Manager chapter. Immediately prior to 
installing the 'INIT' resources, the system searches the NuBus slots looking for 
other device drivers to install. The sRsrcDir data structure in each 

card's configuration ROM describes all devices on that card. For each device 
there is a sRsrcList structure which contains the resource name (sRsrcName) and 
the offset to a table of drivers. These structures are described in the Slot 
Manager chapter. 


For each sResource, the search for drivers during startup takes place in the 
following steps: 


1. The operating system looks for an sRsrc Flags field in the sResource list. 


2. If no sRsrc Flags field exists, or if an sRsrc Flags field exists and 
the field's fOpenAtStart bit is set to 1, the operating system searches 
for a driver, as described below in steps 3 and 4. If the value of 
fOpenAtStart is 0, the operating system does not search for a driver; 
it goes on to the next sResource. 


3. The system searches the sResource list for a driver load record 
(sRsrc_LoadRec)— a routine designed to copy a driver into the Macintosh 
system heap. If such a routine exists, the system copies it from the 
card's ROM to the heap and executes it. The system passes this routine 
a pointer in AO to an seBlock; on exit, the routine must return a handle 
in the seResult field of the same seBlock to the driver it has loaded. 
If the value of the seStatus field is 0, the system then installs the 
new driver. 


4. If there is no driver load record, the system searches the sResource 
list for a driver directory entry (sRsrc DrvrDir). If there is such 
an entry and the directory contains a driver of the type sMac0S68000 
or sMacOS68020, the system reads the driver from the card's ROM and 
installs it in the Macintosh system heap. 


To install a driver, the Macintosh II ROM first loads it into the system heap 
and locks it if the dNeedsLock bit in the driver flags (drvrFlags) word is set. 
It then installs the driver with a DrvrInstall system call and initializes it 
with an Open call. If the driver returns an error from the Open call, it is 
marked closed, the refNum field is cleared in the ioParameter block, and the 
driver is unlocked. Note that this procedure guarantees that driver 
initialization code will be executed before the system starts executing 
applications. 


The video driver used at the beginning of system startup (the one that makes the 
"happy Macintosh" appear) must be taken from a video card's configuration ROM 
because the System file is not yet accessible. If a system contains multiple 
video cards, the one used first is determined by parameter RAM or, by default, 
by selecting the lowest slot number. To override this initial driver, the user 
must install an 'INIT' 31 resource that explicitly closes the driver from the 
configuration ROM and loads a new driver from a file. 
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The unit table data structure has been extended from 48 devices to 64 to 
accommodate installing slot devices. If more than 64 entries are needed, the 
table automatically expands up to a maximum of 128 entries. 


When a driver serves a device that is plugged into a NuBus slot, it needs to 

know the slot number, the sResource ID number and the ExtDevID number. These 

numbers are discussed in the Slot Manager chapter. The Slot Manager provides 

values for five new entries on the end of the Device Control Entry (DCE) data 
structure for each sResource. These new entries are 


byte containing the slot number (dCtlSlot) 

byte containing the RsrcDir ID number for the sResource (dCtlSlotID) 
pointer for the driver to use for the device base address (dCtlDevBase) 
reserved field for future use 

byte containing the external device ID (dCtlExtDev) 


ceooeee 
9MOdQQOY ® 


The Device Control Entry now looks like this: 


AuxDCE = PACKED RECORD 


dCtlDriver: Ptr; {ptr to ROM or handle to RAM driver} 
dCtlFlags: INTEGER; {flags} 
dctlQHdr: QHdr; {driver's i/o queue} 
dCtlPosition: LONGINT; {byte pos used by read and write calls} 
dctlStorage: Handle; {hndl to RAM drivers private storage} 
dCtlRefNum: INTEGER; {driver's reference number} 
dctlCurTicks: LONGINT; {counter for timing system task calls} 
dCtlWindow: Ptr; {ptr to driver's window if any} 
dctlDelay: INTEGER; {number of ticks btwn sysTask calls} 
dCtlEMask: INTEGER; {desk acessory event mask} 
dctlMenu: INTEGER; {menu ID of menu associated with driver} 
dCtlSlot: Byte; {slot} 
dCtlSlotId: Byte; {slot ID} 
dCtlDevBase: LONGINT; {base address of card for driver} 
reserved: LONGINT; {reserved; should be 0} 
dCtlExtDev: Byte; {external device ID} 
fillByte: Byte; {reserved} 
END; {SlotDCE} 
AuxDCEPtr = “AuxDCE; 
AuxDCEHandle = “AuxDCEPtr; 


All Device Control Entries are set before the driver's Open routine is called. 


Use of the base address pointer dCtlDevBase in the DCE is optional. On 


a card 


with multiple instances of the same device, the driver can use this pointer to 


distinguish between devices. 


Because the DCE address is passed to the driver on 


every call from the Device Manager, the presence of this pointer in the DCE 
simplifies location of the correct device. This pointer is the address of the 
base of the card's slot space plus an optional offset obtained from the 
MinorBaseOS field of the sResource. This field frees the driver writer from the 
necessity of locating the hardware for simple slot devices. The system makes no 
other references to it. 
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OPENING SLOT DEVICES 


The low-level PBOpen routine has been extended to let you open devices in NuBus 
slots. A new call has been defined: OpenSlot is the equivalent of PBOpen except 
that it sets the IMMED bit, which signals an extended parameter block. 

FUNCTION OpenSlot(paramBlock: paramBlkPtr; aSync: BOOLEAN) : OsErr; 


If the slot sResource serves a single device (for example, a video device), 
clear all the bits of the ioFlags field and use the following parameter block: 


Parameter block 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
<-- 22 ioRefNum word 
--> 27 ioPermssn byte 
--> 28 ioMix pointer 
--> 32 ioFlags word 
--> 34 ioSlot byte 
--> 35 iold byte 


In the extension fields, ioMix is a pointer reserved for use by the driver open 
routine. The ioSlot parameter contains the slot number of the device being 
opened, in the range 9..$E; if a built-in device is being opened, ioSlot must be 
0. The ioId parameter contains the sResource ID. Slot numbers and sResources 
are discussed in the Slot Manager. 


If the slot sResource serves more than one device (for example, a chain of disk 
drives), set the fMulti bit in the ioFlags field (clearing all other flags bits 
to 0) and use the following parameter block: 


Parameter block 


--> 12 ioCompletion pointer 
<- 16 ioResult word 
--> 18 ioNamePtr pointer 
<-- 22 ioRefNum word 
--> 27 ioPermssn byte 
--> 28 ioMix pointer 
--> 32 ioFlags word 


“2> 34 LoSEBLkPtr pointer 


Here the new parameter ioSEBLkPtr is a pointer to an external parameter block 
(described in the Slot Manager chapter) that is customized for the devices 
installed in the slot. The pointer value is passed to the driver. 
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SLOT DEVICE INTERRUPTS 


Slot interrupts enter the system by way of the Macintosh II VIA2 chip, which 
contains an 8-bit register that has a bit for each slot. This means that there 
is effectively one interrupt line per card. You can tell almost instantly which 
card requested the interrupt, but not which device on the card. To locate the 
interrupt to a device, the Slot Manager provides the polling procedure described 
below. 


The Device Manager maintains an interrupt queue for each slot. The queue 
elements are ordered by priority and contain pointers to polling routines. Upon 
receipt of a slot interrupt the Device Manager goes through the slot's interrupt 
queue, calling each polling routine, until it gets an indication that the 
interrupt has been satisfied. If no such indication occurs, a system error 
dialog is displayed. 


The format for a slot interrupt queue element is the following: 


SQLink EQU 0 ; link to next element (pointer) 
SQType EQU 4 ;queue type ID for validity (word) 
SQPrio EQU 6 ;priority (low byte of word) 

SQAddr EQU 8 ;interrupt service routine (pointer) 


SQParm EQU 12 ;optional Al parameter (long) 


The SQLink field points to the next queue entry; it is maintained by the system. 
The SQType field identifies the structure as an element of a slot interrupt 
queue. It should be set to SIQType. The SQPrio field is an unsigned byte that 
determines the order in which slots are polled and routines are called. Higher 
value routines are called sooner. Priority values 200-255 are reserved for Apple 
devices. The SQAddr field points to the interrupt polling routine. 


eeeClick on the X-Ref button, and refer to Technical Notes #221 & #257.¢ee 


The SQParm field is a value which is loaded into Al before calling an interrupt 
service routine. This could be a handle to the driver's DCE, for example. 
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NEW ROUTINES 


The Device Manager provides two new routines to implement the interrupt queue 
process just described: SIntInstall and SIntRemove. They are described below. 


FUNCTION SIntInstall(sIntQElemPtr: SQElemPtr; theSlot: INTEGER) : OsErr; 


Trap macro _SIntInstalt 


On entry DO: slot number (word) 
AQ: address of slot queue element 
On exit DO: error code 


SIntInstall adds a new element (pointed to by sIntQElemPtr) to the interrupt 
queue for the slot whose number is given in theSlot. As explained in the Slot 
Manager chapter, slots are numbered from 9 to $E. 


Assembly-language note: From assembly language, this routine has the 
following calling sequence (assuming AQ points 
to a slot queue element): 


LEA PollRoutine,Al ;get routine address 
MOVE.L A1,SQAddr (AQ) ;set address 

MOVE .W Prio,SQPrio(AQ) ;set priority 

MOVE.L AlParm,SQParm(AQ) ;save Al parameter 
MOVE .W Slot ,DO ;set slot number 
_SIntInstall ;do installation 


This code causes the routine at label PollRoutine to 
be called as a result of an interrupt from the 
specified slot (9..$E). The Device Manager will 

poll the slot which has the highest priority first if 
two or more slots request an interrupt simultaneously. 


FUNCTION SIntRemove(sIntQElemPtr: SQElLemPtr; theSlot: INTEGER) : OsErr; 


Trap macro —_SIntRemove 


On entry DO: slot number (word) 
AQ: address of slot queue element 
On exit DO: error code 


SIntRemove removes an element (pointed to by sIntQElemPtr) from the interrupt 
queue for the slot whose number is given in theSlot. As explained in the Slot 
Manager chapter, slots are numbered from 9 to $E. 


Assembly-language note: From assembly language, this routine has the 
following calling sequence (assuming AQ points 
to a slot queue element): 


LEA MySQEL,A0 ;pointer to queue element 
_SIntRemove ;remove it 
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This routine lets you remove an interrupt handler 
from the system without causing a crash. 


Your driver polling routine will be called with the following assembly- language 
code: 


MOVE.L AlParm,Al ; load Al Parameter 
JSR PollRoutine ;call polling routine 


Your polling routine should preserve the contents of all registers except Al and 
DO. It should return to the Device Manager with an RTS instruction. DO should 
be set to zero to indicate that the polling routine did not service the 
interrupt, or nonzero to indicate the interrupt has been serviced. The polling 
routine should not set the processor priority below 2, and should return with 
the processor priority equal to 2. The Device Manager resets the VIA2 int flag 
and executes an RTE to the interrrupted task when a polling routine indicates 
that the interrupt is satisfied; otherwise, it calls the next lower-priority 
polling routine for that slot. If none exists, a system error results. 
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SUMMARY OF THE DEVICE MANAGER 


Constants 
CONST 


{ Values for requesting read/write access } 


fsCurPerm = 0; {whatever is currently allowed} 
fsRdPerm = 1; {request to read only} 

fsWrPerm = 2; {request to write only} 
fsRdWrPerm = 3) {request to read and write} 


{ Positioning modes } 


fsAtMark = 0; fat current position} 

fsFromStart = 1; {offset relative to beginning of medium} 
fsFromMark = 3; {offset relative to current position} 
rdVerify = 64; {add to above for read-verify} 


[Volume IV additions] 


{Chooser message values} 


newSelMsg = 12; {new user selections have been made} 
FillListMsg = 13; {fill the list with choices to be made} 
getSelMsg = 14; {mark one or more choices as selected} 
selectMsg = 15; {a choice has actually been made} 
deselectMsg = 16; {a choice has been cancelled} 
terminateMsg = 17; {lets device package clean up} 

buttonMsg = 19; {tells driver a button has been selected} 


{caller values} 


chooserID at) {caller value for the Chooser} 
Data Types 
TYPE 
ParamBlkType = (ioParam, fileParam, volumeParam,cntrlParam) ; 
ParamBlockRec = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
ioTrap: INTEGER; {routine trap} 
ioCmdAddr: Ptr; {routine address} 
ioCompletion: ProcPtr; {completion routine} 
ioResult: OSErr; {result code} 
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ioNamePtr: 
ioVRefNum: 


StringPtr; {driver name} 


INTEGER; 


CASE ParamBlkType OF 


ioParam: 

(ioRefNum: 
ioVersNum: 
ioPermssn: 
ioMisc: 
ioBuffer: 
ioReqCount: 
ioActCount: 
ioPosMode: 


ioPosOffset: 


fileParam: 
. {used 
volumeParam: 
. {used 
cntrlParam: 
(ioCRefNum: 
csCode: 
csParam: 


END; 


DCtlHandle “DCtLPtr; 

DCtlPtr “DCtlEntry; 

DCtlEntry = RECORD 
dctlDriver: 


dCtlFlags: 
dCtlQHdr: 
dCtlPosition: 


dctlStorage: 
dctlRefNum: 
dctlCurTicks: 
dCtlWindow: 
dctlDelay: 


dCtlEMask: 
dctlMenu: 


END; 


{volume reference or } 
{ drive number} 


INTEGER; {driver reference number} 
SignedByte; {not used} 
SignedByte; {read/write permission} 
Ptr; {not used} 
Ptr; {pointer to data buffer} 
LONGINT; {requested number of bytes} 
LONGINT; factual number of bytes} 
INTEGER; {positioning mode} 
LONGINT) ; {positioning offset} 
by the File Manager} 
by the File Manager} 
INTEGER; {driver reference number} 
INTEGER; {type of Control or Status call} 
ARRAY[0..10] OF INTEGER); {control or status } 
{ information} 
Ptr; {pointer to ROM driver or } 
{ handle to RAM driver} 
INTEGER; {flags} 
QHdr; {driver I/0 queue header} 
LONGINT; {byte position used by Read } 
{ and Write calls} 
Handle; {handle to RAM driver's } 
{ private storage} 
INTEGER; {driver reference number} 
LONGINT; {used internally} 
WindowPtr; {pointer to driver's window} 
INTEGER; {number of ticks between } 
{ periodic actions} 
INTEGER; {desk accessory event mask} 
INTEGER {menu ID of menu associated 


{ with driver} 


High-Level Routines 


[Not in ROM] 


FUNCTION OpenDriver (name: Str255; VAR refNum: INTEGER) OSErr; 

FUNCTION CloseDriver (refNum: INTEGER) OSErr; 

FUNCTION FSRead (refNum: INTEGER; VAR count: LONGINT; 
buffPtr: Ptr) OSErr; 
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FUNCTION FSWrite (refNum: INTEGER; VAR count: LONGINT; 
buffPtr: Ptr) : OSErr; 


FUNCTION Control (refNum: INTEGER; csCode: INTEGER; 
csParamPtr: Ptr) : OSErr; 

FUNCTION Status (refNum: INTEGER; csCode: INTEGER; 
csParamPtr: Ptr) : OSErr; 

FUNCTION KillIO (refNum: INTEGER) : OSErr; 


[Volume IV addition] 


FUNCTION Device (message,caller: INTEGER; objName,zoneName: StringPtr; 
pl,p2: LONGINT) : OSErr; 


[Volume V additions] 
FUNCTION OpenSlot (paramBlock: paramBlkPtr; aSync: BOOLEAN) : OsErr; 


FUNCTION SIntInstall (sIntQElemPtr: SQElemPtr; theSlot: INTEGER ) : OsErr; 
FUNCTION SIntRemove (sIntQElemPtr: SQElemPtr; theSlot: INTEGER) : OsErr; 


Low-Level Routines 


FUNCTION PBOpen (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


--> 12 ioCompletion pointer 
ae 16 ioResult word 
--> 18 ioNamePtr pointer 
<-- 24 ioRefNum word 
--> 27 ioPermssn byte 
FUNCTION PBClose (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 24 ioRefNum word 


FUNCTION PBRead (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 

--> 22 ioVRefNum word 

--> 24 ioRefNum word 

--> 32 ioBuffer pointer 
--> 36 ioReqCount long word 
<-- 40 ioActCount long word 
--> 44 ioPosMode word 


<-> 46 ioPosOffset long word 


FUNCTION PBWrite (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 

--> 22 ioVRefNum word 

--> 24 ioRefNum word 

--> 32 ioBuffer pointer 
--> 36 ioReqCount long word 
<-- 40 ioActCount long word 
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--> 44 ioPosMode word 
<-> 46 ioPosOffset long word 
FUNCTION PBControl (paramBlock: ParmBlkPtr; async: BOOLEAN) OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 22 ioVRefNum word 
--> 24 ioRefNum word 
--> 26 csCode word 
--> 28 csParam record 
FUNCTION PBStatus (paramBlock: ParmBlkPtr; async: BOOLEAN) OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 22 ioVRefNum word 
--> 24 ioRefNum word 
--> 26 csCode word 
<-- 28 csParam record 
FUNCTION PBKillIO (paramBlock: ParmBlkPtr; async: BOOLEAN) OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 24 ioRefNum word 
Accessing a Driver's Device Control Entry 
FUNCTION GetDCtlEntry (refNum: INTEGER) DCtlHandle; [Not in ROM] 


Result Codes 
Name 


abortErr 
badUnitErr 
controlErr 
diInsteErr 
dRemovErr 
noErr 
notOpenErr 
openErr 


readErr 
statusErr 
unitEmptyErr 
writErr 


Value 


—27 
—21 
-17 
—26 
—25 

0 
—28 
—23 


-19 
—18 
—22 
—20 


Meaning 


I/O request aborted by KillIO 

Driver reference number doesn't match unit table 
Driver can't respond to this Control call 
Couldn't find driver in resource file 

Attempt to remove an open driver 

No error 

Driver isn't open 

Requested read/write permission doesn't match 
driver's open permission 

Driver can't respond to Read calls 

Driver can't respond to this Status call 

Driver reference number specifies NIL handle in unit table 
Driver can't respond to Write calls 


Assembly-Language Information 


@ SpiInsi 
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Constants 


. 
| 


Flags in trap words 


asnycTrpBit .EQU 10 ;set for an asynchronous call 
noQueueBit .EQU 9 ;set for immediate execution 


| 


; Values for requesting read/write access 


fsCurPerm .EQU 0 ;whatever is currently allowed 

fsRdPerm . EQU 1 ;request to read only 

fsWrPerm .EQU 2 ;request to write only 

fsRdwrPerm .EQU 3 ;request to read and write 

; Positioning modes 

fsAtMark .EQU 0 ;at current position 

fsFromStart .EQU 1 ;offset relative to beginning of medium 

fsFromMark .EQU 3 ;offset relative to current position 

rdVerify -EQU 64 ;add to above for read-verify 

; Driver flags 

dReadEnable . EQU 0 ;set if driver can respond to Read calls 

dwWritEnable .EQU 1 ;set if driver can respond to Write calls 

dCtlEnable .EQU 2 ;set if driver can respond to Control calls 

dStatEnable .EQU 3 ;set if driver can respond to Status calls 

dNeedGoodBye .EQU 4 ;set if driver needs to be called before the 
; application heap is reinitialized 

dNeedTime . EQU 5 ;set if driver needs time for performing a 
; periodic action 

dNeedLock .EQU 6 ;set if driver will be locked in memory as 


| 


; soon as it's opened (always set for ROM drivers) 


; Device control entry flags 


dOpened . EQU 5 ;set if driver is open 
dRAMBased . EQU 6 ;set if driver is RAM-based 
drvrActive .EQU 7 ;set if driver is currently executing 


. 
| 


csCode values for driver control routine 


accRun .EQU 65 ;take the periodic action, if any, for this driver 
goodBye .EQU -1 ;heap will be reinitialized, clean up if necessary 
killCode . EQU 1 ;handle the KillIO call 


. 
| 


Low-order byte of Device Manager traps 


aRdCmd .EQU 2 ;Read call (trap $A002) 
aWrCmd .EQU 3 ;Write call (trap $A003) 


| 


; Offsets from SCC base addresses 


aData . EQU 6 schannel A data in or out 
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aCtl . EQU 2 ‘channel A control 

bData . EQU 4 ‘channel B data in or out 
bctl . EQU 0 schannel B control 
[Volume IV additions] 


; Chooser message values 


newSel . EQU 12 snew user selections have been made 
fillList . EQU 13 ;fill the list with choices to be made 
getSel -EQU 14 ;mark one or more choices as selected 
select .EQU 15 ;a choice has actually been made 
deselect . EQU 16 sa choice has been cancelled 

terminate .EQU 17 ; lets device package clean up 

button . EQU 19 stells driver a button has been selected 


» Caller values 
chooserID . EQU 1 scaller value for the Chooser 
[Volume V additions] 


» Slot Queue Element 


SQLink EQU 0 ; link to next element (pointer) 
SQType EQU 4 ;queue type ID for validity (word) 
SQPrio EQU 6 ;priority (low byte of word) 

SQAddr EQU 8 ;interrupt service routine (pointer) 
SQParm EQU 12 ;optional Al parameter (long) 
STQType EQU 6 ;slot interrupt queue element type 


Standard Parameter Block Data Structure 


qLink Pointer to next queue entry 

qType Queue type (word) 

ioTrap Routine trap (word) 

ioCmdAddr Routine address 

ioCompletion Address of completion routine 

ioResult Result code (word) 

ioVNPtr Pointer to driver name (preceded by length byte) 
ioVRefNum Volume reference number (word) 

ioDrvNum Drive number (word) 


Control and Status Parameter Block Data Structure 


ioRefNum Driver reference number (word) 
csCode Type of Control or Status call (word) 
csParam Parameters for Control or Status call (22 bytes) 


I/O Parameter Block Data Structure 
ioRefNum Driver reference number (word) 
ioPermssn Open permission (byte) 
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ioBuffer Pointer to data buffer 
ioReqCount Requested number of bytes (long) 
ioActCount Actual number of bytes (long) 
ioPosMode Positioning mode (word) 
ioPosOffset Positioning offset (long) 


Device Driver Data Structure 


drvrFlags Flags (word) 

drvrDelay Number of ticks between periodic actions (word) 
drvrEMask Desk accessory event mask (word) 

drvrMenu Menu ID of menu associated with driver (word) 
drvrOpen Offset to open routine (word) 

drvrPrime Offset to prime routine (word) 

drvrCtl Offset to control routine (word) 

drvrStatus Offset to status routine (word) 

drvrClose Offset to close routine (word) 

drvrName Driver name (preceded by length byte) 


Device Control Entry Data Structure 


dctlDriver Pointer to ROM driver or handle to RAM driver 


dCtlFlags Flags (word) 

dctlQueue Queue flags: low-order byte is driver's version number (word) 
dCtlQHead Pointer to first entry in driver's I/0 queue 

dctlQTail Pointer to last entry in driver's I/0 queue 


dCtlPosition Byte position used by Read and Write calls (long) 
dctlStorage Handle to RAM driver's private storage 


dctlRefNum Driver's reference number (word) 

dct lWindow Pointer to driver's window 

dctlDelay Number of ticks between periodic actions (word) 
dCtlEMask Desk accessory event mask (word) 

dct lMenu Menu ID of menu associated with driver (word) 


Structure of Primary Interrupt Vector Table 


autoInt1l Vector to level-1 interrupt handler 
autoInt2 Vector to level-2 interrupt handler 
autoInt3 Vector to level-3 interrupt handler 
autoInt4 Vector to level-4 interrupt handler 
autoInt5 Vector to level-5 interrupt handler 
autoInt6 Vector to level-6 interrupt handler 
autoInt7 Vector to level-7 interrupt handler 


[Volume IV additions] 
Device Package Data Structure 
Byte Value 
BRA.S to offset $10 
Device ID (word) 


0 

2 

4 'PACK' (long word) 
8 $FO00 (—4096) 
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A Version (word) 
C Flags (long word) 
10 Start of driver code 


[Volume V additions] 


Device Control Entry Data Structure 


dctlDriver 
dCtlFlags 
dctlQueue 
dCtlQHead 
dctlQTail 
dCtlPosition 
dctlStorage 
dctlRefNum 
dct lWindow 
dctlDelay 
dCtlEMask 
dctlMenu 
dcttStlot 
dctlStotID 
dCtlDevBase 
reserved 
dCtlExtDev 


Pointer to ROM driver or handle to RAM driver 
Flags (word) 
Queue flags: 
Pointer to first entry in driver's I/O queue 
Pointer to last entry in driver's I/O queue 

Byte position used by Read and Write calls (long) 
Handle to RAM driver's private storage 

Driver's reference number (word) 

Pointer to driver's window 

Number of ticks between periodic actions (word) 
Desk accessory event mask (word) 

Menu ID of menu associated with driver (word) 
Slot number (byte) 

Resource directory ID number for sResource (byte) 
Device base address (pointer) 

Longint reserved for future use (should be Q@) 
External device ID (byte) 


OpenSlot Parameter Blocks 


If fMulti bit in ioFlags = 0: 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
<-- 22 ioRefNum word 
--> 27 ioPermssn byte 
--> 28 ioMix pointer 
--> 32 ioFlags word 
--> 34 ioSlot byte 
--> 35 iold byte 
If fMulti bit in ioFlags = 1: 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
<-- 22 ioRefNum word 
--> 26 ioPermssn byte 
--> 28 ioMix pointer 
--> 32 ioFlags word 
--> 34 ioSEBLkPtr pointer 


Macro Names 


Pascal name 


Macro name 


THE DEVICE 


low-order byte is driver's version number (word) 
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PBRead _Read 


PBWrite _Write 

PBControl _Control 
PBStatus _ Status 
PBKillIO _KillIO 


Volume V additions 


sIntInstall _sIntInstall 
sIntRemove _sIntRemove 


Routines for Writing Drivers 


Routine Jump vector On entry On exit 
Fetch JFetch Al: ptr to device DO: character fetched; bit 15=1 
control entry if last character in buffer 
Stash JStash Al: ptr to device DO: bit 15=1 if last character 
control entry requested 
DO: character to stash 
I0Done JIODone Al: ptr to device 


control entry 
DO: result code (word) 


Variables 

UTableBase Base address of unit table 

JFetch Jump vector for Fetch function 

JStash Jump vector for Stash function 

JIODone Jump vector for I0Done function 

Lvl1DT Level-1 secondary interrupt vector table (32 bytes) 
Lv l2DT Level-2 secondary interrupt vector table (32 bytes) 
VIA VIA base address 

ExtStsDT External/status interrupt vector table (16 bytes) 
SCCWr SCC write base address 

SCCRd SCC read base address 
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Further Reference: 


Resource Manager 

Desk Manager 

File Manager 

OS Utilities 

Start Manager 

Slot Manager 

List Manager Package 

Disk Driver 

Serial Drivers 

Technical Note #36, Drive Queue Elements 

Technical Note #56, Break/CTS Device Driver Event Structure 
Technical Note #71, Finding Drivers in the Unit Table 
Technical Note #108, AddDrive, DrvrInstall and DrvrRemove 
Technical Note #187, Don't Look at ioPosOffset 

Technical Note #197, Chooser Enhancements 

Technical Note #208, Setting and Restoring A5 

Technical Note #221, NuBus Interrupt Latency 

Technical Note #250, AppleTalk Phase 2 on the Macintosh 
Technical Note #257, Slot Interrupt Prio-Technics 

Q & A Stack 

"Macintosh Family Hardware Reference" 

"Designing Cards and Drivers for the Macintosh II and Macintosh SE" 
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